home *** CD-ROM | disk | FTP | other *** search
/ Fritz: All Fritz / All Fritz.zip / All Fritz / FILES / PROGNG_C / DBTOOLC.LZH / README2 < prev    next >
Text File  |  1987-10-27  |  10KB  |  248 lines
  1.        CHANGE SUMMARY: Initial Release Update
  2.  
  3. THE dBASE TOOLS FOR C: the Programmer's Library, Version 1.4
  4.  
  5.  
  6. This README file contains update information about The
  7. Programmer's Library. Check for additional "readme"
  8. files in the various subdirectories on the distribution
  9. disk. The major points are summarized here:
  10.  
  11.   1. New Organization of the Distribution Disk
  12.  
  13.   2. Memory Allocation by DCT1
  14.   
  15.   3. Changes in the syntax if running from within dBASE
  16.   
  17.   4. Notes on Arrays: limits of array sizes and valid array types,
  18.      invalid array checking in the COUNT function
  19.  
  20.   5. Accommodations for logical and date arrays are explained.
  21.  
  22.   6. Error messages may be left on the screen by pressing the 
  23.      ESC key.
  24.  
  25.   7. Some structure changes have been made for those who wish to 
  26.      add their own C functions.
  27.  
  28.   8. The DUMPARRAY function has been enhanced.
  29.  
  30.   9. The use of character return variables is clarified below.
  31.  
  32.   10. Compiler support is clarified.
  33.  
  34.  
  35. These changes are explained more fully in the following paragraphs.
  36. ___________________________________________________________________
  37.  
  38. 1. New organization of distribution disk
  39. The files are distributed slightly differently than with previous 
  40. versions. The following directory gives an explanation of where to
  41. find particular files:
  42.  
  43. Directory       Contents
  44.  
  45. \DBDIR      All files necessary to use The Programmer's Library
  46.             if you do not plan to make your own modifications
  47.             using one of the supported C compilers.
  48.  
  49. \SOURCE     All compiler-independent source files.
  50.  
  51. \LC2        All files required by the Lattice C compiler, 
  52.             version 2.15, which cannot be recreated from
  53.             the files in \SOURCE.
  54.  
  55. \LC3        All files required by the Lattice C compiler, 
  56.             version 3.0, which cannot be recreated from
  57.             the files in \SOURCE.
  58.  
  59. \MS          All files required by the Microsoft C compiler, 
  60.             version 3.0, which cannot be recreated from
  61.             the files in \SOURCE.
  62.  
  63. \AZ          All files required by the Aztec C Prime compiler, 
  64.             which cannot be recreated from the files in \SOURCE.
  65.  
  66.  
  67. Each of the above directories may also contain a README file,
  68. which contains updates to the documentation and/or other relevant
  69. information.
  70.  
  71.  
  72. 2. Install the Tools BEFORE running dBASE
  73.  
  74. DCT1 should be run BEFORE loading dBASE, not from within dBASE 
  75. as described in the manual. Further, the amount of memory you 
  76. expect to need for arrays should be specified in increments of 
  77. 1024 bytes immediately after the program name (0 to 120KB). For 
  78. example, the following command line:
  79.  
  80. DCT1 32
  81.  
  82. installs the Programmer's Library, and allocates approximately 
  83. 32KB of memory for use with arrays. The actual amount of memory 
  84. allocated will depend upon the compiler being used.
  85.  
  86. If the amount of memory needed is not specified, a default of 
  87. 16KB is used with both Lattice versions and with the Microsoft
  88. version, 10KB with the Aztec C Prime version. If you do not expect to 
  89. use arrays at all, and want to use the minimum amount of memory 
  90. required by DCT1, you should specify 0 bytes of array usage as 
  91. follows:
  92.  
  93. DCT1 0
  94.  
  95. If you specify more than the maximum amount of memory allowed for 
  96. arrays, the system will allocate its maximum of 120KB. 
  97.  
  98. What the above means is that the TOTAL amount of storage useable 
  99. by arrays is limited to the amount specified on the command line, 
  100. or the default values. With the version compiled with the LATTICE 
  101. Large Memory Model (\DBDIR\DCT1.EXE on the distribution disk), 
  102. a maximum of 120K can be allocated for arrays in this manner. 
  103.  
  104. The actual maximum size for each of your arrays can be computed 
  105. by knowing the type of array (Character or Numeric) and the total 
  106. amount of storage available.  Numeric arrays require 8 bytes of 
  107. storage for each value plus approximately 100 bytes overhead per 
  108. array. Character arrays require 2 bytes of storage for each value 
  109. plus the total of all the lengths of the elements to be stored in 
  110. the array (each character element has a null terminator which  
  111. also must be counted in its length). Due to alignment restrictions
  112. by the various compilers, these figures may vary by up to 8 bytes 
  113. per allocation.
  114.  
  115. For example, if you specified 32KB, you could have a single 
  116. numeric array with approximately 4000 values, or two numeric 
  117. arrays each with 2000 values, or a character array big enough to 
  118. hold a little less than 100 character variables each 32 bytes 
  119. long, or any similar combination. (See note 3 below.)
  120.  
  121. The function STARRAY now also reports the total amount of 
  122. memory remaining available to the array functions (LATTICE 
  123. versions only).
  124.  
  125.  
  126. 3. Change in the syntax if running from within dBASE
  127.  
  128. If for any reason it becomes desirable to install the Tools
  129. from within dBASE (as earlier versions did), note that
  130. the syntax of the RUN command is slightly different from the 
  131. manual. You will need to RUN a separate copy of COMMAND.COM to 
  132. invoke DCT1 from within dBASE, as follows:
  133.  
  134.      . RUN COMMAND /C DCT1 <n>
  135.  
  136. where <n> is the amount of memory to reserve for arrays (in 
  137. kilobytes). (Be sure that COMSPEC is set to a directory which 
  138. contains a valid copy of COMMAND.COM, or that the path includes 
  139. such a directory.)
  140.  
  141. For example,
  142.  
  143.      . RUN COMMAND /C DCT1 16
  144.      
  145. installs the Programmer's Library and allocates approximately 
  146. 16KB of memory for use with arrays. The actual amount of memory 
  147. allocated will depend upon the compiler being used.
  148.  
  149. When using the AZTEC compiled version of the Programmer's 
  150. Library, it possible to cause memory allocation problems by 
  151. attempting to fill arrays beyond the allocated memory space. For 
  152. this reason, pay careful attention to only create arrays that 
  153. will not overrun the allocated memory. See the table in note 3 
  154. below to determine maximum array sizes. 
  155.  
  156.  
  157. 4. The maximum amount of space that can be consumed by a single 
  158. array is 64KB. The maximum size of individual arrays is a function 
  159. of the type of array and the memory model being used. The following 
  160. table summarizes the restrictions on array sizes:
  161.  
  162.  Memory Model   Array Type    Amount of Memory    Max # elements
  163.  
  164.   Large          Numeric       # elements * 8       8000
  165.   Small          Numeric       # elements * 8       3000
  166.   Large          Character     # elements * 4      16000
  167.   Small          Character     # elements * 2      12000
  168.  
  169. Note also that the amount of memory consumed by each CRARRAY may 
  170. vary from the above rules by 8 or fewer bytes, due to internal 
  171. alignment restrictions imposed by the various compilers. 
  172.  
  173. The COUNT function returns -1 if the <array> parameter is an 
  174. invalid array.
  175.  
  176. 5. Only array types of N (Numeric) and C (Character) are valid 
  177. array types. If arrays of logical or date variables are needed, 
  178. we recommend the use of numeric arrays with 0's (for FALSE) and 
  179. 1's (TRUE) to simulate logical arrays, and the use of character 
  180. arrays to hold the character values of dates, which can then be 
  181. converted, if necessary, using the dBASE CTOD function.
  182.  
  183.  
  184. 6. Pressing the ESC key instead of the return key when dct1 displays 
  185. a message will leave the message on the screen, rather than 
  186. restoring the previous contents of the screen.
  187.  
  188.  
  189. 7. The structure of the dispatch table, ci_DT, in dctmain.h, has 
  190. been modified slightly. The fields F_Type and F_ArgFmt are no 
  191. longer used, and have been omitted from the structure definitions 
  192. in dctmain.h, and from the initializations in dct1.c. 
  193.  
  194. Strings of the form "this is a test" would be parsed as 
  195. "thisisatest". This has been changed, and a new macro, GetString, 
  196. has been added, which should be used instead of GetFunc or 
  197. GetNext when the parameter could be a multiple-word string.
  198.  
  199.  
  200. 8. Pressing any key during a DUMPARRAY display will now abort the 
  201. display.
  202.  
  203.  
  204. 9. An anomaly exists when using character return variables. If the 
  205. length of the string to be returned is less than the length of a 
  206. pre-existing value in the dBASE character variable, the new 
  207. value will be 'stuffed' into the first part of the variable, and 
  208. old characters past the length of the new string will remain. For 
  209. example, if C_C_RESULT contains the string "ABCDEFG", and the 
  210. value "XYZ" is obtained from a character array with GETARRAY, 
  211. C_C_RESULT will then contain "XYZDEFG". Unfortunately, there is 
  212. no way to inform dBASE of the new length of the string from 
  213. within DCT1. The proper way to avoid this problem is to be sure 
  214. to reinitialize C_C_RESULT each time the length of its value may 
  215. vary. For example, if you expect the lengths of the character 
  216. elements to vary, the following dBASE code will return the values 
  217. of the first 10 elements from the array STRINGS:
  218.  
  219.    i = 0
  220.    do while i < 10
  221.       c_c_result = space(50)
  222.       call cfunc with 'setdvar c'
  223.       call cfunc with c_c_result
  224.       call cfunc with 'getarray strings, '+str(i)
  225.       ? i, c_c_result
  226.       i = i+1
  227.    enddo
  228.  
  229.  
  230. 10. Revised compiler support
  231. This version of dBASE Tools for C supports the following C 
  232. compilers:
  233.  
  234.             Lattice version 3.x  (Large model)
  235.             Microsoft 4.0        (Large model)
  236.             Aztec C Prime        (Small model)
  237.  
  238. The DCT1.EXE file located in the \DBDIR directory on your
  239. distribution disk was created with Lattice version 3.2. If
  240. you want to modify the library or create your own library,
  241. you will need to follow the instructions given in the README
  242. file in the appropriate directory (see change #1 for 
  243. information on the organization of the distribution disk.)
  244.  
  245. Before creating a new DCT1.LIB library file, delete DCT1.LIB 
  246. if one was previously created.
  247.  
  248.